/* libfake437 - a library for the rendering of code page 437 `graphics'
 * Copyright (C) 2008, 2009, 2010 Jack Kelly <endgame.dos@gmail.com>
 *
 * This library is free software: you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation, either version 3 of
 * the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library.  If not, see <http://www.gnu.org/licenses/>.
 */

/**
 ** @node F437Display Operations
 ** @chapter F437Display Operations
 **
 ** The @code{F437Display} provides a layer-oriented interface to a
 ** @code{F437Surface}.
 **/

#ifndef FAKE437_DISPLAY_H
#define FAKE437_DISPLAY_H

#ifdef __cplusplus
extern "C" {
#endif

/**
 ** @deftypefun F437DisplayLayer* f437_display_layer_new @
 **   (int @var{left},                                   @
 **    int @var{top},                                    @
 **    int @var{width},                                  @
 **    int @var{height})
 **
 ** @deftypefunx F437DisplayLayer* f437_display_layer_try_new @
 **   (int @var{left},                                        @
 **    int @var{top},                                         @
 **    int @var{width},                                       @
 **    int @var{height})
 **
 ** Create a F437DisplayLayer with an initial reference count of
 ** 1. @code{f437_display_layer_new} calls @code{abort()} on
 ** allocation failure, while @code{f437_display_layer_try_new} just
 ** returns @code{NULL}.
 **
 ** @end deftypefun
 **/
F437DisplayLayer* f437_display_layer_new(int left, int top,
                                         int width, int height);
F437DisplayLayer* f437_display_layer_try_new(int left, int top,
                                             int width, int height);

/**
 ** @deftypefun F437DisplayLayer* f437_display_layer_ref @
 **   (F437DisplayLayer* @var{layer})
 **
 ** @deftypefunx void f437_display_layer_unref @
 **   (F437DisplayLayer* @var{layer})
 **
 ** Increment/decrement the reference count of a display
 ** layer. There's no funny business going on with borrowed references
 ** or anything - always unref a pointer just before it goes out of
 ** scope.
 **
 ** @end deftypefun
 **/
F437DisplayLayer* f437_display_layer_ref(F437DisplayLayer* layer);
void f437_display_layer_unref(F437DisplayLayer* layer);

/**
 ** @deftypefun F437Display* f437_display_new @
 **   (SDL_Surface*    @var{surface},         @
 **    const F437Font* @var{font})
 **
 ** @deftypefunx F437Display* f437_display_try_new @
 **   (SDL_Surface*    @var{surface},         @
 **    const F437Font* @var{font})
 **
 ** @deftypefunx SDL_Surface* f437_display_free @
 **   (F437Display* @var{display})
 **
 ** Create and destroy @code{F437Display}s. The @code{SDL_Surface*}
 ** passed to @code{f437_display_new} will not be owned by the
 ** display. It will be returned by @code{f437_display_free}.
 **
 ** @end deftypefun
 **/
F437Display* f437_display_new(SDL_Surface* surface,
                              const F437Font* font);
F437Display* f437_display_try_new(SDL_Surface* surface,
                                  const F437Font* font);
SDL_Surface* f437_display_free(F437Display* display);

/**
 ** @deftypefun void f437_display_insert_layer @
 **   (F437Display*      @var{display},        @
 **    F437DisplayLayer* @var{layer},          @
 **    int               @var{n})
 **
 ** @deftypefunx F437DisplayLayer* f437_display_get_layer @
 **   (F437Display* @var{display},                        @
 **    int          @var{n})
 **
 ** @deftypefunx void f437_display_remove_layer @
 **   (F437Display* @var{display},              @
 **    int          @var{n})
 **
 ** Add/examine/remove a layer from a display. When inserting, the new
 ** layer is inserted just before layer @var{n}. For get/remove, layer
 ** @var{n} is returned/removed. For @code{f437_display_get_layer},
 ** unref the pointer when finished.
 **
 ** @end deftypefun
 **/
void f437_display_insert_layer(F437Display* display, F437DisplayLayer* layer,
                               int n);
F437DisplayLayer* f437_display_get_layer(F437Display* display, int n);
void f437_display_remove_layer(F437Display* display, int n);

/**
 ** @deftypefun void f437_display_swap_layers @
 **   (F437Display* @var{display},            @
 **    int          @var{n},                  @
 **    int          @var{m})
 **
 ** Swap layers @var{n} and @var{m} in the display.
 **
 ** @end deftypefun
 **/
void f437_display_swap_layers(F437Display* display, int n, int m);

/**
 ** @deftypefun void f437_display_push_layer @
 **   (F437Display*      @var{display},      @
 **    F437DisplayLayer* @var{layer})
 **
 ** @deftypefunx F437DisplayLayer* f437_display_peek_layer @
 **   (F437Display* @var{display})
 **
 ** @deftypefunx void f437_display_pop_layer @
 **   (F437Display* @var{display})
 **
 ** Treat the display as a stack of layers. For
 ** @code{f437_display_peek_layer}, be sure to unref the returned
 ** pointer when finished.
 **
 ** @end deftypefun
 **/
void f437_display_push_layer(F437Display* display, F437DisplayLayer* layer);
F437DisplayLayer* f437_display_peek_layer(F437Display* display);
void f437_display_pop_layer(F437Display* display);

/**
 ** @deftypefun void f437_display_draw @
 **   (F437Display* @var{display})
 **
 ** Redraw the underlying surface based on @var{display}'s current
 ** contents.
 **
 ** @end deftypefun
 **/
void f437_display_draw(F437Display* display);

#ifdef __cplusplus
}
#endif

#endif
